---
title: "Chat widget"
description: "Learn how to embed the widget in your app"
icon: "rocketchat"
---

<img src="/widget/example.png" alt="Widget demo" />



The chat widget enables you to interact with the AI customer support chatbot from your dashboard and see the changes in real-time. Open is a React web app that you can embed in your web app.

There are several ways you can integrate the chat widget into your application/webpage.


<CardGroup cols={2}>
  <Card title="As a JavaScript File" href='#using-simple-js-script' icon="js">Copy & Paste into your HTML file, simple and east to use</Card>
  <Card title='As a React Component (via npm)' href='#as-a-react-component' icon='react'>With advanced options such as custom UI components</Card>
</CardGroup>

### Using simple js script (Copy & Paste)

1. By using CDN script into your HTML file.
   ```html
   <script src="https://unpkg.com/@openchatai/widget@latest/dist-embed/script.js"></script>
   ```
   This will automatically register a new function called `initOpenWidget` on the global window object.

2. Init the widget (when document fully loads) by calling the `initOpenWidget` function and passing the required options.
    There are plenty of options that you can pass to the widget, you can find them [here](#options)
   ```html
   <script>
      const options = {
        /** ## Basic and required options ## */
        token: "your_organization_token_goes_here", // (required) Settings -> Metadata -> Token
        initialMessages: ["Hey! happy to help."], // (optional) Messages that will be first present when the chat widget is initialized

        /** ## User identification options (optional) ## */
        user: {
          name: "John Doe",
          email: "john@doe.com",
          avatar: "https://example.com/avatar.png",
          phone: "123456789",
          customData: {
            // any custom data you want to send to the Open backend, for example:
            "key1": "value1",
          }
        }

        // This widget supports AMAZING features and options. See the options documentation for more details.
      }
      window.addEventListener("DOMContentLoaded", ()=> initOpenScript(options)); // window.onload
   </script>
   ```

### As a React Component

1. Install the widget from npm.

   <Tabs>
     <Tab title="npm">
     ```bash
      npm install @openchatai/widget 
      ```
      </Tab>
     <Tab title="yarn">
     ```bash
      yarn add @openchatai/widget 
      ```
      </Tab>
     <Tab title="pnpm">
     ```bash 
     pnpm add @openchatai/widget 
     ```
     </Tab>
   </Tabs>

2. Use the Component inside your application

```jsx
import { Widget, WidgetRoot, WidgetPopover } from "@openchatai/widget"; 
import "@openchatai/widget/dist/style.css";

const options = {
  /** ## Basic and required options ## */
  token: "your_organization_token_goes_here", // (required) Settings -> Metadata -> Token
  initialMessages: ["Hey! happy to help."], // (optional) Messages that will be first present when the chat widget is initialized

  /** ## User identification options (optional) ## */
  user: {
    name: "John Doe",
    email: "john@doe.com",
    avatar: "https://example.com/avatar.png",
    phone: "123456789",
    customData: {
      // any custom data you want to send to the Open backend, for example:
      "key1": "value1",
    }
  },

  // This widget supports AMAZING features and options. See the options documentation for more details.
}

function Widget(){
  return (
    <WidgetRoot options={options}>
      <Widget /> // the inline chat widget
      <WidgetPopover /> // optional, if you want to use the popover
    </WidgetRoot>
  )
}
```

## Available options

The chat widget is highly customizable, here is a list of all the available options:

<ResponseField name="Options" type="Object">
  <Expandable title="properties">
    <ResponseField name="token" type="string" required>
      Your organization token, you can find it in the settings page of your organization
    </ResponseField>
    <ResponseField name="user" type="object">
      The user object that will be used to identify the user/contact of the chat. read more about [identifying chat users/contacts](#identifying-chat-userscontacts)
      <Expandable title="properties">
        <ResponseField name="name" type="string">
          The name of the user
        </ResponseField>
        <ResponseField name="email" type="string">
          The email of the user
        </ResponseField>
        <ResponseField name="avatar" type="string">
          The avatar of the user
        </ResponseField>
        <ResponseField name="phone" type="string">
          The phone number of the user
        </ResponseField>
        <ResponseField name="customData" type="object">
          Any custom data that you want to send to the backend
        </ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="initialMessages" type="array">
      The message that will be first present when the widget is initialized
    </ResponseField>
    <ResponseField name="triggerSelector" type="string">
      The selector of the element that will trigger the widget when clicked, if not set, a default trigger will be added to the root element (will show on bottom right of the screen)
    </ResponseField>
    <ResponseField name="apiUrl" type="string">
      The backend url of the widget api (default: https://api-v2.opencopilot.so/backend), you can use your own backend if you have one (open source or self hosted)
    </ResponseField>
    <ResponseField name="headers" type="Object">
      An object of headers that will be sent with every request to your backend (can be used to authenticate your api requests)
    </ResponseField>
    <ResponseField name="containerProps" type="Object">
      An object of props that will be passed to the container div, it's helpful if you want to style the widget <a href="/widget/styling">learn more about styling the chat widget</a>
    </ResponseField>
    <ResponseField name="socketUrl" type="string">
      The url of the socket url that will be used to send and receive messages, it's helpful if you want to use your own socket server (open source or self hosted)
    </ResponseField>
    <ResponseField name="components" type="Object">
      List of components that will be used to render any UI component. <a href="/widget/not-gen-ui">learn more about responding with UI</a>
    </ResponseField>
    <ResponseField name="debug" type="boolean">
      If true, the widget will log all the messages and events to the console and to the chat ui (default: false)
    </ResponseField>
    <ResponseField name="onHandoff" type="function">
      A function that will be called when the user is handed off to a human agent. read more about [handoff](/resources/human-handoff)
    </ResponseField>
    <ResponseField name="defaultOpen" type="boolean">
      If true, the widget/chat will be opened by default (default: false) and the triggerSelector will not be added to the root element
    </ResponseField>
  </Expandable>
</ResponseField>


## Identifying chat users/contacts

One of the helpful options in the chat widget is the ability to identify the user/contact of the chat. This is useful if you want to track the usage of the chat widget.

To start identifying the user/contact, you can pass the `user` object as an option to the chat widget, for example:

```jsx
const options = {
  initialMessages: ["Hey! happy to help."], 
  token: "your_organization_token_goes_here", // Settings -> Metadata -> Token
  user: {
    name: "your_user_name",
    email: "your_user_email",
    avatar: "your_user_avatar_url",
    phone: "your_user_phone",
    customData: {
      // any custom data you want to send to the Open backend
      "key1": "value1",
    }
  },
}
```

Read more about the contact APIs <a href="/api-reference/contacts/introduction">here</a>

## FAQ

<AccordionGroup>
  <Accordion title="The widget is not showing up">
    Make sure that the `triggerSelector` is correct and the element exists in
    the dom,instead you can set `defaultOpen` to `true` to make the widget open by default.
    if that did not work, please [open an issue on our GitHub repo](https://github.com/openchatai/OpenCopilot/issues/new)
  </Accordion>

  <Accordion title="The widget is so small">
    The widget is responsive and it's width is set to 100% by default of the container, you can change that by passing the
    `containerProps` option and setting the width to whatever you want.
  </Accordion>
</AccordionGroup>